React createPortal: Dominando a Criação de Portais e a Manipulação de Eventos

No desenvolvimento web moderno com React, criar interfaces de usuário que se integram perfeitamente com a estrutura do documento subjacente é crucial. Embora o modelo de componentes do React seja excelente para gerenciar o DOM virtual, às vezes precisamos renderizar elementos fora da hierarquia normal de componentes. É aqui que entra o createPortal. Este guia explora o createPortal em profundidade, cobrindo seu propósito, uso e técnicas avançadas para manipular eventos e construir elementos de UI complexos. Abordaremos considerações de internacionalização, melhores práticas de acessibilidade e armadilhas comuns a serem evitadas.

O que é o React createPortal?

createPortal é uma API do React que permite renderizar os filhos de um componente React em uma parte diferente da árvore DOM, fora da hierarquia do componente pai. Isso é particularmente útil para criar elementos como modais, tooltips, menus suspensos e sobreposições que precisam ser posicionados no nível superior do documento ou dentro de um contêiner específico, independentemente de onde o componente que os aciona está localizado na árvore de componentes do React.

Sem o createPortal, alcançar isso geralmente envolve soluções alternativas complexas, como manipular o DOM diretamente ou usar posicionamento absoluto com CSS, o que pode levar a problemas com contextos de empilhamento, conflitos de z-index e acessibilidade.

Por que usar o createPortal?

Aqui estão as principais razões pelas quais o createPortal é uma ferramenta valiosa em seu arsenal React:

• Estrutura DOM Aprimorada: Evita aninhar componentes profundamente no DOM, resultando em uma estrutura mais limpa e gerenciável. Isso é especialmente importante para aplicações complexas com muitos elementos interativos.
• Estilização Simplificada: Posiciona facilmente elementos em relação à viewport ou a contêineres específicos sem depender de truques complexos de CSS. Isso simplifica a estilização e o layout, especialmente ao lidar com elementos que precisam sobrepor outro conteúdo.
• Acessibilidade Melhorada: Facilita a criação de UIs acessíveis, permitindo que você gerencie o foco e a navegação por teclado independentemente da hierarquia de componentes. Por exemplo, garantindo que o foco permaneça dentro de uma janela modal.
• Melhor Manipulação de Eventos: Permite que os eventos se propaguem corretamente do conteúdo do portal para a árvore React, garantindo que os ouvintes de eventos anexados aos componentes pais ainda funcionem como esperado.

Uso Básico do createPortal

A API createPortal aceita dois argumentos:

1. O nó React (JSX) que você deseja renderizar.
2. O elemento DOM onde você deseja renderizar o nó. Idealmente, este elemento DOM deve existir antes que o componente que usa o createPortal seja montado.

Aqui está um exemplo simples:

Exemplo: Renderizando um Modal

Digamos que você tenha um componente de modal que deseja renderizar no final do elemento body.

            import React from 'react';
import ReactDOM from 'react-dom';

function Modal({ children, isOpen, onClose }) {
  if (!isOpen) return null;

  const modalRoot = document.getElementById('modal-root'); // Assumes you have a <div id="modal-root"></div> in your HTML

  if (!modalRoot) {
    console.error('Modal root element not found!');
    return null;
  }

  return ReactDOM.createPortal(
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
        {children}
      </div>
    </div>,
    modalRoot
  );
}

export default Modal;

            

              
                Copy
              
            
          

Explicação:

• Importamos ReactDOM porque createPortal é um método do objeto ReactDOM.
• Assumimos que existe um elemento DOM com o ID modal-root em seu HTML. É aqui que o modal será renderizado. Certifique-se de que este elemento exista. Uma prática comum é adicionar uma <div id="modal-root"></div> logo antes da tag de fechamento </body> em seu arquivo index.html.
• Usamos ReactDOM.createPortal para renderizar o JSX do modal no elemento modalRoot.
• Usamos e.stopPropagation() para evitar que o evento onClick no conteúdo do modal acione o manipulador onClose na sobreposição. Isso garante que clicar dentro do modal não o feche.

Uso:

            import React, { useState } from 'react';
import Modal from './Modal';

function App() {
  const [isModalOpen, setIsModalOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
      <Modal isOpen={isModalOpen} onClose={() => setIsModalOpen(false)}>
        <h2>Modal Content</h2>
        <p>This is the content of the modal.</p>
        <button onClick={() => setIsModalOpen(false)}>Close</button>
      </Modal>
    </div>
  );
}

export default App;

            

              
                Copy
              
            
          

Este exemplo demonstra como renderizar um modal fora da hierarquia normal de componentes, permitindo que você o posicione de forma absoluta na página. Usar o createPortal desta maneira resolve problemas comuns com contextos de empilhamento e permite criar facilmente um estilo de modal consistente em toda a sua aplicação.

Manipulação de Eventos com createPortal

Um dos principais benefícios do createPortal é que ele preserva o comportamento normal de borbulhamento de eventos do React. Isso significa que eventos originados no conteúdo do portal ainda se propagarão pela árvore de componentes do React, permitindo que os componentes pais os manipulem.

No entanto, é importante entender como os eventos são tratados quando cruzam a fronteira do portal.

Exemplo: Manipulando Eventos Fora do Portal

            import React, { useState, useRef, useEffect } from 'react';
import ReactDOM from 'react-dom';

function OutsideClickExample() {
  const [isOpen, setIsOpen] = useState(false);
  const dropdownRef = useRef(null);
  const portalRoot = document.getElementById('portal-root');

  useEffect(() => {
    function handleClickOutside(event) {
      if (dropdownRef.current && !dropdownRef.current.contains(event.target)) {
        setIsOpen(false);
      }
    }

    document.addEventListener('mousedown', handleClickOutside);

    return () => {
      document.removeEventListener('mousedown', handleClickOutside);
    };
  }, [dropdownRef]);

  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle Dropdown</button>
      {isOpen && portalRoot && ReactDOM.createPortal(
        <div ref={dropdownRef} style={{ position: 'absolute', top: '50px', left: '0', border: '1px solid black', padding: '10px', backgroundColor: 'white' }}>
          Dropdown Content
        </div>,
        portalRoot
      )}
    </div>
  );
}

export default OutsideClickExample;

            

              
                Copy
              
            
          

Explicação:

• Usamos uma ref para acessar o elemento do dropdown renderizado dentro do portal.
• Anexamos um ouvinte de evento mousedown ao document para detectar cliques fora do dropdown.
• Dentro do ouvinte de evento, verificamos se o clique ocorreu fora do dropdown usando dropdownRef.current.contains(event.target).
• Se o clique ocorreu fora do dropdown, nós o fechamos definindo isOpen como false.

Este exemplo demonstra como manipular eventos que ocorrem fora do conteúdo do portal, permitindo criar elementos interativos que respondem às ações do usuário no documento circundante.

Casos de Uso Avançados

createPortal não se limita a modais e tooltips simples. Pode ser usado em vários cenários avançados, incluindo:

• Menus de Contexto: Renderizar dinamicamente menus de contexto perto do cursor do mouse ao clicar com o botão direito.
• Notificações: Exibir notificações no topo da tela, independentemente da hierarquia de componentes.
• Popovers Personalizados: Criar componentes de popover personalizados com posicionamento e estilização avançados.
• Integração com Bibliotecas de Terceiros: Usar createPortal para integrar componentes React com bibliotecas de terceiros que exigem estruturas DOM específicas.

Exemplo: Criando um Menu de Contexto

            import React, { useState, useRef, useEffect } from 'react';
import ReactDOM from 'react-dom';

function ContextMenuExample() {
  const [contextMenu, setContextMenu] = useState(null);
  const menuRef = useRef(null);

  useEffect(() => {
    function handleClickOutside(event) {
      if (menuRef.current && !menuRef.current.contains(event.target)) {
        setContextMenu(null);
      }
    }
    document.addEventListener('mousedown', handleClickOutside);
    return () => {
      document.removeEventListener('mousedown', handleClickOutside);
    };
  }, [menuRef]);

  const handleContextMenu = (event) => {
    event.preventDefault();
    setContextMenu({
      x: event.clientX,
      y: event.clientY,
    });
  };

  const portalRoot = document.getElementById('portal-root');

  return (
    <div onContextMenu={handleContextMenu} style={{ border: '1px solid black', padding: '20px' }}>
      Right-click here to open context menu
      {contextMenu && portalRoot && ReactDOM.createPortal(
        <div
          ref={menuRef}
          style={{
            position: 'absolute',
            top: contextMenu.y,
            left: contextMenu.x,
            border: '1px solid black',
            padding: '10px',
            backgroundColor: 'white',
          }}
        >
          <ul>
            <li>Option 1</li>
            <li>Option 2</li>
            <li>Option 3</li>
          </ul>
        </div>,
        portalRoot
      )}
    </div>
  );
}

export default ContextMenuExample;

            

              
                Copy
              
            
          

Explicação:

• Usamos o evento onContextMenu para detectar cliques com o botão direito no elemento de destino.
• Prevenimos o aparecimento do menu de contexto padrão usando event.preventDefault().
• Armazenamos as coordenadas do mouse na variável de estado contextMenu.
• Renderizamos o menu de contexto dentro de um portal, posicionado nas coordenadas do mouse.
• Incluímos a mesma lógica de detecção de clique externo do exemplo anterior para fechar o menu de contexto quando o usuário clica fora dele.

Considerações de Acessibilidade

Ao usar o createPortal, é crucial considerar a acessibilidade para garantir que sua aplicação seja utilizável por todos.

Gerenciamento de Foco

Quando um portal é aberto (por exemplo, um modal), você deve garantir que o foco seja movido automaticamente para o primeiro elemento interativo dentro do portal. Isso ajuda os usuários que navegam com um teclado ou leitor de tela a acessar facilmente o conteúdo do portal.

Quando o portal fecha, você deve retornar o foco para o elemento que acionou a abertura do portal. Isso mantém um fluxo de navegação consistente.

Atributos ARIA

Use atributos ARIA para fornecer informações semânticas sobre o conteúdo do portal. Por exemplo, use aria-modal="true" no elemento do modal para indicar que é uma caixa de diálogo modal. Use aria-labelledby para associar o modal ao seu título, e aria-describedby para associá-lo à sua descrição.

Navegação por Teclado

Garanta que os usuários possam navegar pelo conteúdo do portal usando o teclado. Use o atributo tabindex para controlar a ordem do foco, e certifique-se de que todos os elementos interativos são alcançáveis com o teclado.

Considere prender o foco dentro do portal para que os usuários não possam navegar acidentalmente para fora dele. Isso pode ser alcançado ouvindo a tecla Tab e movendo programaticamente o foco para o primeiro ou último elemento interativo dentro do portal.

Exemplo: Modal Acessível

            import React, { useState, useRef, useEffect } from 'react';
import ReactDOM from 'react-dom';

function AccessibleModal({ children, isOpen, onClose, labelledBy, describedBy }) {
  const modalRef = useRef(null);
  const firstFocusableElementRef = useRef(null);
  const [previouslyFocusedElement, setPreviouslyFocusedElement] = useState(null);
  const modalRoot = document.getElementById('modal-root');

  useEffect(() => {
    if (isOpen) {
      // Save the currently focused element before opening the modal.
      setPreviouslyFocusedElement(document.activeElement);

      // Focus the first focusable element in the modal.
      if (firstFocusableElementRef.current) {
        firstFocusableElementRef.current.focus();
      }

      // Trap focus within the modal.
      function handleKeyDown(event) {
        if (event.key === 'Tab') {
          const focusableElements = modalRef.current.querySelectorAll(
            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
          );
          const firstFocusableElement = focusableElements[0];
          const lastFocusableElement = focusableElements[focusableElements.length - 1];

          if (event.shiftKey) {
            // Shift + Tab
            if (document.activeElement === firstFocusableElement) {
              lastFocusableElement.focus();
              event.preventDefault();
            }
          } else {
            // Tab
            if (document.activeElement === lastFocusableElement) {
              firstFocusableElement.focus();
              event.preventDefault();
            }
          }
        }
      }

      document.addEventListener('keydown', handleKeyDown);

      return () => {
        document.removeEventListener('keydown', handleKeyDown);
        // Restore focus to the element that had focus before opening the modal.
        if(previouslyFocusedElement && previouslyFocusedElement.focus) {
          previouslyFocusedElement.focus();
        }
      };
    }
  }, [isOpen, previouslyFocusedElement]);

  if (!isOpen) return null;

  return ReactDOM.createPortal(
    <div
      className="modal-overlay"
      onClick={onClose}
      aria-modal="true"
      aria-labelledby={labelledBy}
      aria-describedby={describedBy}
      ref={modalRef}
    >
      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
        <h2 id={labelledBy}>Modal Title</h2>
        <p id={describedBy}>This is the modal content.</p>
        <button ref={firstFocusableElementRef} onClick={onClose}>
          Close
        </button>
        {children}
      </div>
    </div>,
    modalRoot
  );
}

export default AccessibleModal;

            

              
                Copy
              
            
          

Explicação:

• Usamos atributos ARIA como aria-modal, aria-labelledby e aria-describedby para fornecer informações semânticas sobre o modal.
• Usamos o hook useEffect para gerenciar o foco quando o modal abre e fecha.
• Salvamos o elemento atualmente focado antes de abrir o modal e restauramos o foco para ele quando o modal fecha.
• Prendemos o foco dentro do modal usando um ouvinte de evento keydown.

Considerações de Internacionalização (i18n)

Ao desenvolver aplicações para um público global, a internacionalização (i18n) é uma consideração crítica. Ao usar o createPortal, há alguns pontos a serem lembrados:

• Direção do Texto (RTL/LTR): Garanta que sua estilização acomode tanto idiomas da esquerda para a direita (LTR) quanto da direita para a esquerda (RTL). Isso pode envolver o uso de propriedades lógicas em CSS (por exemplo, margin-inline-start em vez de margin-left) e a definição apropriada do atributo dir no elemento HTML.
• Localização do Conteúdo: Todo o texto dentro do portal deve ser localizado para o idioma preferido do usuário. Use uma biblioteca de i18n (por exemplo, react-intl, i18next) para gerenciar as traduções.
• Formatação de Números e Datas: Formate números e datas de acordo com a localidade do usuário. A API Intl fornece funcionalidades para isso.
• Convenções Culturais: Esteja ciente das convenções culturais relacionadas a elementos de UI. Por exemplo, o posicionamento de botões pode diferir entre culturas.

Exemplo: i18n com react-intl

            import React from 'react';
import { FormattedMessage } from 'react-intl';

function MyComponent() {
  return (
    <div>
      <FormattedMessage id="myComponent.greeting" defaultMessage="Hello, world!" />
    </div>
  );
}

export default MyComponent;

            

              
                Copy
              
            
          

O componente FormattedMessage do react-intl recupera a mensagem traduzida com base na localidade do usuário. Configure o react-intl com suas traduções para diferentes idiomas.

Armadilhas Comuns e Soluções

Embora o createPortal seja uma ferramenta poderosa, é importante estar ciente de algumas armadilhas comuns e como evitá-las:

• Elemento Raiz do Portal Ausente: Certifique-se de que o elemento DOM que você está usando como raiz do portal exista antes que o componente que usa o createPortal seja montado. Uma boa prática é colocá-lo diretamente no index.html.
• Conflitos de Z-Index: Tenha cuidado com os valores de z-index ao posicionar elementos com createPortal. Use CSS para gerenciar contextos de empilhamento e garantir que o conteúdo do seu portal seja exibido corretamente.
• Problemas de Manipulação de Eventos: Entenda como os eventos se propagam através do portal e manipule-os apropriadamente. Use e.stopPropagation() para evitar que eventos acionem ações não intencionais.
• Vazamentos de Memória: Limpe adequadamente os ouvintes de eventos e referências quando o componente que usa createPortal for desmontado para evitar vazamentos de memória. Use o hook useEffect com uma função de limpeza para conseguir isso.
• Problemas Inesperados de Rolagem: Portais às vezes podem interferir no comportamento esperado de rolagem da página. Garanta que seus estilos não estejam impedindo a rolagem e que os elementos modais não causem saltos na página ou comportamento inesperado de rolagem quando abrem e fecham.

Conclusão

React.createPortal é uma ferramenta valiosa para criar UIs flexíveis, acessíveis e de fácil manutenção no React. Ao entender seu propósito, uso e técnicas avançadas para manipulação de eventos e acessibilidade, você pode aproveitar seu poder para construir aplicações web complexas e envolventes que proporcionam uma experiência de usuário superior para um público global. Lembre-se de considerar as melhores práticas de internacionalização e acessibilidade para garantir que suas aplicações sejam inclusivas e utilizáveis por todos.

Seguindo as diretrizes e exemplos deste guia, você pode usar com confiança o createPortal para resolver desafios comuns de UI e criar experiências web impressionantes.